\section{Framework Manual}
\label{section:framework_manual}

    \subsection{Latex Entwicklungsumgebungen}
    \label{subsection:latex_entwicklungsumgebungen}

        Zum Bearbeiten des Dokumentationsframeworks und Erstellen neuer
        Dokumente wird eine Entwicklungsumgebung benötigt. Die Wahl der
        bevorzugten Entwicklungsumgebung aus der Vielzahl an verfügbaren Latex
        Umgebungen ist jedem Benutzer freigestellt.\par\bigskip
        
        Eine weit verbreitete \acf{IDE} ist Eclipse und wird an dieser Stelle
        auch empfohlen. In Anhang
        \ref{subsection:eclipse_ide_installationsanleitung} ist dazu eine
        Installationsanleitung aufgeführt, die alle benötigten Komponenten
        beschreibt. Bei Verwendung anderer Entwicklungsumgebungen
        sollte darauf geachtet werden, dass die Konventionen welche
        im Dokument "`Konventionen zur Benutzung des
        Dokumentationsframework"' aufgeführt sind eingehalten
        werden.\par\bigskip

        Des Weiteren wird zum Erstellen der Dokumentation eine Latex
        Distribution benötigt. Dabei sollten Folgende vom Betriebssystem abhängige
        Distributionen verwendet werden:
        
        \begin{itemize}
          \item TexLive (Unix)
          \item MikTex (Windows)
        \end{itemize}

    \subsection{Designentscheidungen}
    \label{subsection:designentscheidungen}
    
        Damit mehrere Entwickler, welche an unterschiedlichen Arbeitspaketen
        eine gemeinsame Dokumentation schreiben können, müssen im Voraus
        etliche Maßnahmen und Überlegungen getroffen werden. Aus weitgreifenden
        Erfahrungswerten haben sich folgende Ansprüche an das Framework
        herausgestellt:
        
        \begin{itemize}
            \item Pro Arbeitspaket existiert eine eigenständige Dokumentation.
            \item Das Layout der Dokumente muss vorgegeben werden.
            \item Es müssen globale Konventionen vorliegen.
            \item Die Dokumente müssen unabhängig von unterschiedlichen
                   \acsp{IDE} erstellt werden können.
            \item Die Benutzung muss so einfach wie möglich gestaltet werden.
            \item Alle einzelnen Dokumente müssen zu einer Gesamtdokumentation
                   zusammengefasst werden können.
            \item Es muss möglich sein nur bestimmte einzelne Dokumente zu einer
                   gemeinsamen Dokumentation zusammenzuführen.
        \end{itemize}\bigskip
        
        Diese Designentscheidungen ermöglichen eine einfache und strukturierte
        Zusammenarbeit und bieten etliche benötigte Features bei der Erstellung
        gemeinsamer Dokumentationen. Der Größte Vorteil ist die Flexibilität, je
        nach Bedarf einzelne Dokumente zusammenzufassen.\par\bigskip
            
    \subsection{Struktur des Frameworks}
    \label{subsection:struktur_des_frameworks}

        \subsubsection{Projekte und Dokumente}
        \label{subsubsection:projekte_und_dokumente}
        
            Zur Realisierung des Frameworks wurden mehrere Projekte erzeugt, welche
            in Folgender Übersicht dargestellt und beschrieben sind.\bigskip
        
            \dirtree{%
            .1 /.
                .2 DocConventions.
                    .3 document.pdf.
                    .3 \ldots.
                .2 DocManual.
                    .3 document.pdf.
                    .3 \ldots.
                .2 DocMaster.
                .2 DocMasterExample.
                    .3 merge.sh.
                    .3 DocMaster.tar.gz.
                    .3 \ldots.
                .2 DocTemplate.
            }\bigskip    
            
            \begin{description}
                \item[DocConventions] ~\\In diesem Ordner befinden sich die Latex
                sourcen des Dokuments "`Konventionen zur Benutzung des
                Dokumentationsframework"'. Hier sind die Konventionen
                beschrieben an die sich alle Entwickler halten müssen um ein einheitliches
                Format garantieren zu können.
                \item[DocManual] ~\\In diesem Ordner befinden sich die Latex
                sourcen des Dokuments "`Dokumentationsframework"'. (Dieses
                Dokument)
                \item[DocMaster] ~\\In diesem Ordner befindet sich die Vorlage der
                Latex sourcen zur Erstellung eines Gesamtdokumentes.
                \item[DocMasterExample] ~\\In diesem Ordner befindet sich ein
                Beispiel wie ein Gesamtdokument aus einzelnen Dokumenten erzeugt
                werden kann. Eine genaue Beschreibung dazu befindet sich in
                Abschnitt \ref{subsection:dokumentationen_zusammenfassen}.
                \item[DocTemplate] ~\\In diesem Ordner befindet sich ein Template
                um eine einzelne Dokumentation erstellen zu können
            \end{description}
        
        \subsubsection{Verzeichnisstruktur des Templates}
        \label{subsubsection:verzeichnisstruktur_des_templates}
        
            Im Folgenden ist eine Übersicht über die Dateien des Frameworks gegeben. Die
            Dateien und Ordner werden kurz im einzelnen beschrieben.\par\bigskip
            
            Das Framework ist so angelegt, dass im Regelfall nur noch der Inhalt
            geschrieben werden muss. Alle Dokumenteigenschaften sind festgelegt
            und müssen nicht mehr bearbeitet werden.\par\bigskip
        
            \dirtree{%
            .1 DocTemplate.
                .2 content.
                    .3 images.
                        .4 htwlogo.pdf.
                    .3 misc.
                    .3 sections.
                        .4 00\_BeispielEinleitung.tex.
                        .4 01\_BeispielHauptteil.tex.
                        .4 02\_BeispielSchluss.tex.
                    .3 acronyms.tex.
                    .3 appendix.tex.
                    .3 bibliography.bib.
                    .3 content.tex.
                    .3 glossary.tex.
                    .3 history.tex.
                    .4 settings.tex.
                .2 document.tex.
                .2 htwsek.cls.
                .2 htwsek.sty.
                .2 Makefile.
            }\bigskip
            
            
            \begin{description}
                \item[document.tex] ~\\ Sie liegt im Hauptverzeichnis und stellt die
                Hauptdatei dar. In ihr werden alle *.tex Dateien je nach Einstellung
                includiert und zusammengefügt. Die Datei sollte nicht verändert werden.
                \item[htwsek.cls] ~\\ Zusammen mit der Datei htwsek.sty bildet
                sie das htwsek package, welches in document.tex eingebunden
                wird. Die Datei sollte nicht verändert werden.
                \item[htwsek.sty] ~\\ Sie enthält alle Einstellungen zum
                gesamten htwsek Package. Die Datei sollte nicht verändert
                werden.
                \item[./content] ~\\ Der Ordner enthält alle Dateien, welche verändert
                werden können.
                \item[./content/images] ~\\ In diesem Ordner werden alle für das Dokument
                relevanten Bilder hinterlegt, gegebenenfalls können weitere Unterordner angelegt werden.
                \item[./content/misc] ~\\ In diesen Ordner können alle sonstigen Dokumente
                und Dateien gespeichert werden, welche \zB im Anhang des Dokumentes
                eingebunden werden.
                \item[./content/sections] ~\\ In diesem Ordner können *.tex Dateien angelegt
                werden. Für Jede Section innerhalb des Dokumentes soll eine eigene Datei
                angelegt werden. Zur besseren Übersicht werden die Dateien in der selben
                Reihenfolge wie sie im Dokument auftreten durchnummeriert.
                \item[acronyms.tex] ~\\ Hier werden alle Abkürzungen definiert. Die Datei
                ist je nach Einstellung optional.
                \item[appendix.tex] ~\\ Hier werden alle Dokumente, Tabellen, Bilder\ldots 
                die im Anhang erscheinen sollen aufgeführt. Die Datei ist je nach
                Einstellung optional.
                \item[bibliography.bib] ~\\ In dieser Datei werden alle Quellen aufgelistet,
                welche im Literaturverzeichnis auftreten sollen. Die Datei ist je nach
                Einstellung optional.
                \item[content.tex] ~\\ Damit eine neue Section Datei im Ordner sections im
                Dokument auftaucht, muss sie hier eingebunden werden. Bis auf diese
                Definitionen sollte in dieser Datei nichts stehen.
                \item[glossary.tex] ~\\ Alle Einträge des Glossars sind hier aufgelistet.
                Die Datei ist je nach Einstellung optional.
                \item[history.tex] ~\\ Alle Änderungen, die von Bearbeitern vorgenommen
                werden sollten in dieser Datei dokumentiert werden. Die Datei ist je nach
                Einstellung optional.
                \item[settings.tex] ~\\ In dieser Datei werden Einstellungen
                über das gesamte Dokument vorgenommen. Es können \zB
                Einstellungen getroffen werden, welche automatisch generierten Listen
                angezeigt werden sollen. Weitere Informationen befinden sich im
                Kapitel \ref{subsubsection:settings}.
            \end{description}

    \subsection{Verwendung des Templates}
    \label{subsection:verwendung_des_templates}
    
        \subsubsection{Settings}
        \label{subsubsection:settings}
        
            Alle für ein Dokument notwendigen Einstellungen können in der Datei
            settings.tex vorgenommen werden. Es kann angegeben werden ob
            Folgende Listen erstellt werden sollen, sowie ob sie auf einer
            separaten Seite erscheinen sollen:
            
            \begin{itemize}
              \item Abkürzungsverzeichnis
              \item Anhang
              \item Literatur- und Quellenverzeichnis
              \item Glossar
              \item Dokumenthistorie
            \end{itemize}
            
            Des Weiteren kann der Titel des Dokuments, Vorlesung und die Autoren
            eingetragen werden. Die Vorgehensweise bei den Einstellungen ist in
            der Datei dokumentiert und leicht verständlich und muss daher an
            dieser Stelle nicht weiter erklärt werden.\par\bigskip
            
            Sollte ein Verzeichnis wie \zB das Abkürzungsverzeichnis in den
            Settings deaktiviert worden sein, kann auch die Datei acronyms.tex
            aus dem Projektverzeichnis entfernt werden. Diese Option vermeidet
            unter anderem bei Verwendung eines Versionierungssystems das
            einchecken von leeren Dateien.
        
        \subsubsection{htwsek Package}
        \label{subsubsection:htwsek_package}
        
            Das htwsek Package dient dazu ein einheitliches Layout und
            definierte Befehle vorzugeben. Ohne dieses Package ist eine
            einheitliche Dokumentation nicht möglich. Sofern alle
            Teildokumentationen dieses Package verwenden ist ein einheitliches
            Layout garantiert.\par\bigskip
            
            Zusätzlich zu den Latex Standardbefehlen wurden hier weitere auf das
            Framework bezogene Befehle definiert, welche im Folgenden aufgeführt
            sind:

            \begin{description}
            \item[\textbackslash{zB}]~\\
                Dieser Befehl sollte für die Abkürzende Schreibweise \zB
                verwendet werden. Er verhindert einen automatischen
                Zeilenumbruch innerhalb der Abkürzung.
            \item[\textbackslash{heading$\lbrace\langle$Überschrift$\rangle\rbrace$}]~\\
                Dieser Befehl erstellt eine Überschrift ohne diese in das
                Inhaltsverzeichnis mit aufzunehmen und dient lediglich dazu ein
                weiteres Gliederungswerkzeug zur Verfügung zu stellen.
            \item[\textbackslash{historyline$\lbrace\langle$Datum$\rangle\rbrace\lbrace\langle$Autor$\rangle\rbrace\lbrace\langle$Kommentar$\rangle\rbrace$}]~\\
                Dieser Befehl erstellt einen neuen Eintrag in die
                Dokumentenhistorie und sollte ausschließlich in der Datei
                history.tex verwendet werden.
            \item[\textbackslash{supersection$\lbrace\langle$Titel$\rangle\rbrace\lbrack\langle$Autor$\rangle\rbrack$}]~\\
                Dieser Befehl sollte in einer einzelnen Dokumentation
                nicht verwendet werden. Er dient dazu in einer aus
                mehreren Dokumenten erzeugten Dokumentation die
                ursprünglichen Dokumente voneinander abzugrenzen. Es wird
                ein Kapitel erstellt mit dem Titelnamen und Angabe der
                Autoren. Dabei ist es maximal möglich 9 Autoren anzugeben.
            \end{description}

            Des Weiteren wurden neue Spaltentypen zur Verwendung in Tabellen
            erstellt. Deren Anwendung wird im Dokument "`Konventionen zur
            Benutzung des Dokumentationsframework"' genauer dargestellt.
            
            \begin{itemize}
              \item[C\{3cm\}] Text ist horizontal zentriert im 3cm breiten Feld.
              \item[L\{3cm\}] Text ist linksbündig im 3cm breiten Feld.
              \item[R\{3cm\}] Text ist rechtsbündig im 3cm breiten Feld.
            \end{itemize}
                      
            Diese Erweiterungen sollen die Verwendung des Frameworks
            automatisieren, vereinheitlichen und eine vereinfachte Benutzung
            ermöglichen.
                        
        \subsubsection{Erstellen einer neuen Dokumentation}
        \label{subsubsection:erstellen_einer_neuen_dokumentation}
        
            Aufgrund dessen, dass beim Erstellen einer neuen Dokumentation aus
            dem Template einiges berücksichtigt werden muss, wird hier die
            Vorgehensweise detailliert erläutert und hingewiesen worauf geachtet
            werden muss:\bigskip
            
            \begin{enumerate}
              \item Prüfen ob die eigene Entwicklungsumgebung den Forderungen im
              Dokument "`Konventionen zur Benutzung des
              Dokumentationsframework"' entspricht.
              \item Eine Kopie des DocTemplate Projektes erstellen. Darauf
              achten, dass die neueste Version verwendet wird.
              \item Es sollten lediglich Dateien im Ordner
              \textit{./DocTemplate/content} verändert werden.
              \item In der Datei \textit{./DocTemplate/content/settings.tex}
              müssen die Angaben zum Dokument eingetragen werden (lecturetitle,
              doctitle, docauthor, pdfauthor).
              \item Falls schon bekannt ist welche automatisch generierten
              Verzeichnisse benutzt werden sollen können diese in der selben
              Datei dementsprechend angepasst werden.
              \item In Nächsten Schritt werden die Sections angelegt, dazu im
              Ordner \textit{./DocTemplate/content/sections} für jede Section
              eine neue Datei anlegen. Zwei Beispieldateien existieren bereits zur
              Orientierung. Es sollte darauf geachtet werden, dass die Dateien
              nummeriert sind wie sie später im Dokument auftreten. Zudem
              sollten keine Leerzeichen im Dateinamen vorhanden sein.
              \item Die Sections werden jetzt in der Datei
              \textit{./DocTemplate/content/content.tex} eingetragen und somit
              in das Dokument eingebunden. Die beiden Beispielsections werden auch hier
              zur Orientierung beispielhaft eingebunden.
              \item Die selbst angelegten Section Dateien können nun mit Inhalt
              gefüllt werden. Dabei ist zu beachten, dass die definierten
              Konventionen im Dokument "`Konventionen zur Benutzung des
              Dokumentationsframework"' eingehalten werden.
              \item Verwendete Bilder können in den Ordner
              \textit{./DocTemplate/content/images} gespeichert werden.
              \item Sonstige Dokumente können in dem Ordner
              \textit{./DocTemplate/content/misc} gespeichert werden.
              \item Letztendlich kann das Makefile mit dem Target all ausgeführt
              werden und die korrekte Funktion geprüft werden.
            \end{enumerate}
        
    \subsection{Dokumentationen zusammenfassen}
    \label{subsection:dokumentationen_zusammenfassen}
    
        \textcolor{red}{!!!Achtung dieser Abschnitt befindet sich noch in
        Bearbeitung!!!}\par\bigskip
    
        In diesem Kapitel wird beschrieben wie aus mehreren Dokumentationen,
        welche das DocTemplate benutzen ein gemeinsames Dokument erstellt werden
        kann.\par\bigskip
        
        Das Projekt DocMasterExample zeigt beispielhaft das Zusammenführen von
        mehreren Dokumenten. Im Folgenden ist die Vorgehensweise genau
        erläutert:
        
        \begin{enumerate}
          \item Dokumentationen in einen gemeinsamen Ordner kopieren
          \item Die beiden Dateien merge.sh, config.cfg und DocMaster.tar.gz
          ebenfalls in den selben Ordner kopieren.
          \item Die Datei config.cfg wie unten beschrieben anpassen.
          \item Das Skript merge.sh ausführen.
        \end{enumerate}\par\bigskip
        
        \heading{Merge Skript}
        
            Das Skript merge.sh dient dazu mehrere Dokumente automatisiert
            zusammenzufügen. Dazu ist es notwendig die dazugehörige config.cfg
            einzustellen. Folgende Einstellungsmöglichkeiten sind gegeben:
    
            \newpage
    
            \begin{description}
            \item[DOCUMENTS=(DocManual DocConventions)]~\\
                Hier werden die Ordner der einzelnen Dokumentationen angegeben.
            \item[DOCUMENT\_TITLE="Master Dokument"]~\\
                Hier wird der Titel des neuen Dokumentes angegeben.
            \item[LECTURE\_TITLE="Software-Entwicklung für
            Kommunikationsnetze"]~\\
                Hier wird der Vorlesungstitel des neuen Dokumentes angegeben.
            \item[PDF\_TITLE="SEK 2012"]~\\
                Hier wird der pdf Titel des neuen Dokumentes angegeben.
            \item[TARGET\_FOLDER\_NAME="output"]~\\
                Hier wird der Ausgabe Ordner angegeben
            \item[FRAMEWORK\_NAME="DocMaster.tar.gz"]~\\
                Hier wird der Dateiname des Archivs, welches aus dem Projekt
                DocMaster erstellt wurde angegeben.
            \end{description}

    \subsection{Erstellen der pdf Datei}
    \label{subsection:erstellen_der_pdf_datei}

        Die pdf Datei kann unabhängig von einer Entwicklungsumgebung mit
        dem Makefile erstellt werden. Dabei können folgende Targets benutzt
        werden:\par\bigskip
        
        \begin{description}
            \item[all] ~\\ 
            Erstellt das pdf und entfernt anschließend alle temporären Dateien die beim
            Buildvorgang entstehen.
            \item[keeptemp] ~\\ 
            Erstellt das pdf ohne temporäre Dateien zu löschen.
            \item[clean] ~\\ 
            Entfernt alle beim Buildvorgang entstandenen temporären Dateien.
            \item[cleanall]~\\ 
            Entfernt alle beim Buildvorgang entstandenen temporären Dateien sowie das
            erstellte pdf.
        \end{description}\par\bigskip
            
        Das Makefile gibt Fehler beim Buildvorgang standardmäßig aus. Sollten dennoch
        zum Debuggen mehr Informationen benötigt werden können diese der Datei
        document.log, welche im selben Verzeichnis erstellt wird, entnommen werden.
            
            
            